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EDIT:  A FORTRAN  PROGRAM  MAINTENANCE  SYSTEM 
FOR  THE  TEXAS  INSTRUMENTS  ASC-7 


INTRODUCTION 


The  Texas  Instruments  Advanced  Scientific  Computer 
(ASC)  is  a large-scale  digital  computer  which  was  installed 
at  the  Naval  Research  Laboratory  in  April  1976.  Its  vector 
arithmetic  capability  and  massive  central  memory  make  it 
attractive  for  use  in  solving  large  numerical  problems. 
While  the  ASC  was  being  used  to  develop  involved  fluid 
mechanics  programs,  the  need  for  some  procedure  to 
automatically  update  programs  became  apparent.  This 
deficiency  led  to  the  development  of  a MACRO  program,  EDIT, 
which  generates  the  control  cards  a user  needs  to  update  a 
program  library.  One  EDIT  call  and  a set  of  Texas 
Instruments  Source  Management  System  (SMS)  directives  allow 
a programmer  to  perform  a program  update  which,  if  done 
manually  using  individual  Job  Specification  Language  (JSL) 
statements,  would  require  approximately  80  control  cards. 

This  documentation  assumes  that  the  reader  has  some 
familiarity  with  both  the  Texas  Instruments  Job 
Specification  Language  and  their  Source  Management  System. 
Users  may  consult  the  JSL  Reference  Manual  and  the  Source 
Management  System  User’s  Guide  for  further  clarification; 
both  of  these  manuals  are  available  through  NRL  Code  1722. 

EDIT  was  modeled  on  a similar  program  used  on  the  CDC 
6000  computers  at  the  David  Taylor  Naval  Ship  Research  and 
Development  Center  (DTNSRDC).  This  program,  also  called 
EDIT,  was  developed  by  Mel  Haas  of  DTNSRDC,  Code  1843,  in 
1972. 

Not*:  Maniueript  mibiiiittad  Ptbniarjr  16,  1979. 
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DESCRIPTION 


The  EDIT  macro  utilizes  Tl-supplied  software  (eg.,  SMS, 
CIFER,  FTN,  PDSQSH,  etc.)  to  automate  the  maintenance  of 
FORTRAN  and  RATFOR*  routines.  EDIT  stores  the  source  code, 
object  code,  and  load  module  for  a given  program  as 
ASC-cataloged  files  with  a user-specified  number  of 
versions . 

To  use  EDIT  to  maintain  a program  the  user  must  first 
catalog  a node  (i.e.,  filename)  in  the  ASC  tree-structured 
file  catalog  system.  The  user  may  then  use  EDIT  to  perform 
a ’’creation  run"  (indicated  by  EDIT' a OLDSRC  and  OLDOBJ 
parameters)  to  establish  a program  library.  EDIT  will  add 
three  sons  to  the  user-supplied  node:  SRCLIB,  OBJLIB,  and 
LOADLIB,  for  the  source  code,  object  code,  and  load  module, 
respectively.  These  nodes  will  have  partial  access  control 
and  full  son-add  control'*’ . The  maximum  number  of  versions 
of  the  files  is  specified  by  the  MXVR  parameter  on  the 
initial  macro  call. 

EDIT  will  catalog  files  containing  the  source  code, 
object  code,  and  load  module,  depending  on  the  values  of  the 
EDIT  parameters  lEDIT  and  CAT.  However,  these  files  will 
not  be  cataloged  if  any  of  the  software  called  by  EDIT  ends 
with  a termination  code  which  Indicates  a fatal  error.  Each 
time  a new  version  of  a file  is  cataloged,  it  is 
automatically  flagged  by  the  system  as  the  version  to  be 
used  by  the  next  EDIT  run.  When  the  user-specified  number 
of  versions  has  been  cataloged,  the  oldest  version  will  be 
replaced  by  the  new  version.  Thus,  a programmer  may  update 
and  maintain  programs  simply  by  supplying  update  information 
to  EDIT.  All  file  manipulation  and  library  updating  are 
managed  by  the  EDIT  macro. 


* RATlonal  FORTRAN  preprocessor,  see:  Kernighan  and 
Plauger,  "Software  Tools,"  Addison-Wesley  (1976). 

■*■  These  terms  are  used  to  define  specific  characteristics 
of  a node.  They  control  who  may  access  the  node  and  who  may 
add  sons  beneath  the  node. 
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INPUT  TO  EDIT 


Input  to  EDIT  is  in  the  form  of  SMS  directives  which 
may  either  follow  the  EDIT  call  or  be  in  a file  named  by  the 
EDIT  parameter  EDTINPUT.  An  SMS  $0PTI0N  card  is  not 
required,  as  one  is  automatically  supplied  by  EDIT  (^OPTION 
A,B,D,Lsl).  If  the  user  chooses  to  override  the  default 
$OPTION  card,  the  A,  B,  and  D options  must  still  be 
specified  to  insure  that  all  libraries  will  be  properly 
updated.  The  user  is  also  cautioned  that  a deck  which  is 
deleted  from  the  source  library  (SRCLIB)  is  not 
automatically  deleted  from  the  object  library  (OBJLIB) . 
This  situation  seldom  arises,  and  may  be  remedied  by  using 
the  EDITKILL  macro  to  delete  the  object  code. 


EDIT  PARAMETERS 


The  format  of  the  EDIT  call  is  as  follows; 


/>JEDIT)6PATH 


i 

1 

0 

2 

1 

e 

,IEDIT» 

2 

,MXVR- 

e 

3 

e 

• 

64  ^ 

(YES 

(YES 

, 

,OLDOBJ- 

NO 

NO 

OLDSRC« 


YES 
NO  S' 


TAPE  ( YES 

DTYP- ^ , RATFOR-  | NO  J , FTNOPT- ( * ) , 

PAD 


FTVERS-* , SPACE»<integer>, FTNTIME«<integer>, FOSYS 
LNKOPT- ( * ) , EDITLIST«<name>, LNKINPUT«<name> , EDTINPOT»<name> 


YES 

NO 

REL 

KEEP 


The  quantities  between  the  square  brackets  are  all 
optional;  the  default  values  are  underlined.  The  meaning 
of  each  of  the  parameters  is  given  below. 

PATH  Existing  pathname  of  program  to  be  edited. 

lEDIT  0 - Perform  source  update. 

1 - Same  as  lEDITsO,  plus  compile  updated 
routines . 

2 • Same  as  lEDITsI,  plus  update  object 
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MXVR 

CAT 

OLDOBJ 


OLDSRC 


DTYP 


RATFOR 


FTNOPT, 

FIVERS, 

LNKOPT 


SPACE, 

FTNTIME 


EDITLIST 


LMKINPUT 


EDTINPUT 


library . 

3 - Same  as  IEDIT32,  plus  build  a new  loaa 
module. 

Number  of  versions  of  files  to  be  kept.  This 
parameter  is  meaningful  only  for  the  first 
EDIT  run  having  CATsYES. 

Command  to  catalog  new  files  if  the  run  is 
successful . 

Indicates  whether  object  code  has  previously 
been  cataloged  by  EDIT.  Should  be  set  to  NO 
until  after  the  first  time  EDIT  is  used  with 
lEDIT  2 and  CAT*YES.  Thereafter  the  default 
value  of  OLDOBJsYES  may  be  used. 

Similar  to  OLDOBJ  except  that  it  applies  to 
the  source  file;  OLDSRC  should  be  set  to  NO 
until  after  the  first  time  EDIT  is  run  with 
CATsYES  U.e.,  a ’’creation  run"). 

File  storage  device  desired.  This  parameter 
may  be  different  for  successive  EDIT  runs, 
but  is  meaningful  only  when  CATsYES. 

Instructs  EDIT  that  this  run  updates  decks 
written  in  RATFOR.  Each  RATFOR  program  must 
be  preceded  by  a card  with  a sharp  sign  in 
column  1 to  initiate  RATFOR  processing. 

See  FTN  and  LNK  macros  for  FORTRAN  and 
LINKAGE  EDITOR  options.  System  default 
options  will  be  supplied  if  these  parameters 
are  omitted . 

Identical  to  FTN  SPACE  and  FTNTIME 
parameters.  System  defaults  will  be  supplied 
when  SPACE  or  FTNTIME  (or  both)  are  omitted. 

Used  to  name  print  file.  If  this  parameter 
is  omitted,  the  print  file  name  will  be 
EDIT.PRT. 

Names  an  optional  input  file  to  the  LINKAGE 
EDITOR.  This  file  is  required  only  if  the 
user  desires  to  supply  routines  to  the 
LINKAGE  EDITOR  which  exist  on  external 
libraries. 

Access  name  of  file  containing  the  SMS 
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directives.  If  this  parameter  is  omitted,  it 
is  assumed  that  SMS  directives  immediately 
follow  the  EDIT  call  card. 

FOSYS  Controls  printing  of  the  EDIT  output  file: 

YES  - Print  output  file. 

NO  - Do  not  print  output  file;  it  will 
remain  with  the  access  name  EDIT.PRT  unless  a 
different  access  name  was  specified  by  using 
the  EDITLIST  parameter. 

REL  - Release  the  output  file. 

KEEP  - Print  the  output  file,  but  do  not 
release  it. 


EXAMPLES 

ESTABLISHING  A PROGRAM  LIBRARY 


/ JOB 
/ USERMAC 
/ LIMIT  8AN0*30 

/ EDIT  EXAMPLE/PATH/NAME»CrLD(58J=NOfOL3SRC=NOtIE3IT  = 2 
IMOOSET  EXAMPLEfUSERaJOEUSER 

(DECK  EXMAINiLANG-FORTRANtUSER=JdEUSER t ACTI9N=A00 
PROGRAM  EXMAIN 
C 

C MAIN  PROGRAM  FOR  EXAMPLES 

C 

X » 3. 

Y = 2. 

Z » X*Y 

CALL  EXSUBCX«Y»Z) 

STOP 

END 

tOECK  OUMMYfLANG«FORTRANtUSER>JOEUSERf ACTION^ADO 
SUBROUTINE  DUMMY 
C 

C THIS  IS  A DUMMY  SUBROUTINE 
C IT  WILL  BE  REMOVED  LATER 

C 

RETURN 

END 

/ EOJ 


This  example  establishes  a source  library  at  pathname 
EXAMPLE/PATH/NAME/3RCLIB,  and  an  object  library  at  pathname 
EXAMPLE/PATH/NAME/OBJLIB.  The  node  EXAMPLE/PATH/NAME  was 
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previously  cataloged  by  the  user.  The  USERMAC  statement 
allows  the  user's  job  to  access  the  macro  library  which 
contains  EDIT.  lEDIT  is  set  to  2 to  inhibit  load  module 
creation,  since  the  main  program  calls  a subroutine  not  yet 
in  the  library.  The  OLDOBJ  and  OLDSRC  parameters  are  both 
set  to  NO  to  indicate  that  neither  OBJECT  nor  SOURCE 
libraries  have  previously  been  cataloged  for  this  particular 
program  node. 


ADDING  A DECK  TO  AN  EXISTING  LIBRARY 


/ JOB 
/ USERNAC 
/ LIKIT  BAND*30 

/ EDIT  EXAMPLE/PATH/NAMEfRATFORsYES 
IMOOSET  UPOATEl (USER=JOEUSER 

lOECK  EXSUB,LANGsRATF(5R,USER  = JOEUSERfACTION  = AOO 
f THIS  CARO  FLAGS  RATFOR  DECK 

SUBROUTINE  EXSUBCXtYtZ) 

C 

C SUBROUTINE  FOR  EXAMPLES 
C 

R s X*X^Y«Y 

IF  <R  .EQ.  n.)  RETURN  A THE  SHARP  SIGN 
IF  CR  .GE.  Z)  A ALLOWS  USERS  TO 

C A COMWEMT  more  freely 

Z « SINCZ) 

X » 0. 

Y * 0. 

3 

ELSE  Z * COSCZ) 

RETURN 
END 
I EOJ 


This  example  adds  a deck  to  the  program  library  created 
in  the  first  example.  The  RATFORsYES  option  is  used  to 
inform  EDIT  that  this  run  contains  references  to  DECKS  which 
are  written  in  RATFOR.  The  card  with  the  sharp  sign  in 
column  1 is  a flag  to  the  RATFOR  processor  that  RATFOR  code 
follows.  FORTRAN  and  RATFOR  decks  may  be  freely 
Interspersed,  since  the  END  card  of  each  RATFOR  program 
turns  the  RATFOR  processor  off.  The  default  EDIT  option 
(IEDITs3)  is  used  in  this  case  to  allow  a load  module  to  be 
built,  since  this  run  supplies  the  subroutine  which  was 
missing  in  the  first  example.  The  load  module  will  be 
cataloged  at  pathname  EXAMPLE/PATH/NAME/LOADLIB. 


6 


MAKING  A CORRECTION  TO  AN  EXISTING  PROGRAM 


/ JOB 
/ USERMAC 
/ LIMIT  8AN0*30 
/ EDIT  example/path/name 
IMOOSET  UPOATE2tUSER»JANEUSER 
(DECK  EXMAINtUSER-JANEUSER 
^REPLACE  EXMAIN  7 
Z=X*Y 

tOECK  DUMMY, ACTIONaOEL 
/ EOJ 


This  example  shows  how  the  user  would  replace  line  7 of 
the  main  program  in  the  first  example  with  the  desired  line, 
ZsX*Y.  The  source  code  for  the  dummy  routine  is  also 
deleted.  Since  the  default  EDIT  option  is  used  (IEDIT=3), 
all  libraries,  including  the  load  module,  would  reflect  the 
change.  However,  the  object  code  for  the  deck  DUMMY  will 
remain  on  the  object  library,  as  mentioned  earlier.  The 
EDITKILL  macro  example  shows  how  to  remove  the  unneeded 
object  code. 


EXECUTING  AN  EXISTING  PROGRAM 


/ JOB 

/ ASG  SYS.LMgD,EXAMPLE/PATH/NAME/L(JAOLIBfUSE  = SHR 
/ FXQT 
/ EOJ 


This  example  shows  how  to  execute  the  program  developed 
in  the  previous  three  examples.  Since  the  load  module  was 
assigned  with  the  access  name  SYS.LMOD,  the  FXQT  macro  may 
be  used  to  accomplish  a standard  FORTRAN  execution. 


EDIT  UTILITY  MACROS 


Several  macros  have  been  written  which  perform  support 
functions  not  directly  performed  by  the  EDIT  macro.  These 
macros  enable  users  to  conveniently  perform  tasks  such  as 
automatically  inserting  $DECK  cards  into  files  of  FORTRAN 
code,  punching  decks,  etc.  In  the  following  descriptions. 
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the  quantities  between  the  brackets  are  all  optional;  the 
default  values  are  underlined. 


EDITCATV 


EDITCATV  is  the  lower  level  macro  which  EDIT  uses  to 
catalog  its  files.  Users  may  call  EDITCATV  explicitly  after 
an  EDIT  execution  to  catalog  the  new  libraries  at  a pathname 
different  from  the  one  used  on  the  EDIT  call.  The  CAT=NO 
option  must  be  used  to  accomplish  this.  There  are  no 
defaults  for  any  of  the  EDITCATV  parameters. 

EDITCATV  PARAMETERS 


/)JEDITCATV>JPATH,IEDI'r,DTYP,MXVR 


PATH  An  existing  pathname.  The  new  EDIT  files 

will  be  cataloged  beneath  this  node  using  the 
standard  EDIT  names  SRCLIB,  OBJLIB,  and 
LOADLIB. 

lEDIT  Must  be  identical  to  the  value  of  lEDIT  used 
in  the  EDIT  execution  which  preceeds 
EDITCATV. 

DTYP  Device  type  for  the  new  EDIT  files.  Legal 

values  are  TAPE  or  PAD. 

MXVR  Integer  which  specifies  the  maximum  number  of 

files  to  be  kept  as  backup. 

EDITCATV  EXAMPLE 

/ JOB 
/ USeRMAC 
/ LIMIT  BAN0»3r 

/ EDIT  EXAMPLE/PATH/NAMEiCAT=NO 
IHOOSET  UP0ATE3#USeR»JANcUSEa 
lOECK  EXMAINtUSERsJANEUSER 
IREPLACE  EXMAIN  5 
X * 4. 

/ EDITCATV  NEW/PATH/NAME»3fPAD»2 
/ EOJ 

This  example  modifies  the  old  library  and  catalogs  it 
at  a new  pathname.  The  old  library  will  remain  unchanged. 
The  new  files  will  reside  on  PAD,  having  a maximum  of  two 
versions.  IEDITs3  was  selected  to  agree  with  the  default 
value  used  in  the  preceedlng  EDIT  execution. 
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EDITDECK 


EDITDECK  is  used  to  punch  a deck  of  a 
maintained  by  EDIT. 

EDITDECK  PARAMETERS 


program 


YES 

/)iEDITDECK)tfPATH  ,FOSYS-  ,DECKNAME»<naine>,VERS=<integer> 

NO 


PATH 

FOSYS 

DECKNAME 


VERS 


Pathname  of  the  program  libraries. 

YES  - Produce  a deck  of  punched  cards. 

NO  - Produce  a file  called  COMPILE 
Used  to  name  a specific  deck  in  the  SRCLIB 
for  which  source  code  is  desired.  If 
DECKNAME  is  not  specified,  all  decks  on  the 
SRCLIB  will  be  selected. 

Version  of  the  SRCLIB  to  be  used. 

EDITDECK  EXAMPLE 


/ JOB 
/ USERMAC 
/ LIMIT  BAND*30 
/ EDITDECK  EXAMPLE/PATH/NAME 
/ EOJ 


The  above  example  shows  how  to  obtain  a punched  deck  of 
the  source  library  built  in  the  previous  examples. 


EDITFIX 


EDITFIX  is  used  when  the  current  version  of  a program 
becomes  unusable  for  some  reason  (faulty  tape,  etc.).  It 
replaces  the  current  version  with  an  earlier  version.  If 
the  VERS  parameter  is  set  to  +0,  EDITFIX  will  replace  the 
current  version  with  a new  copy  of  the  current  version. 
This  feature  may  be  used  to  move  tape  resident  files  to 
disc,  or  to  make  a new  copy  of  an  often-used  tape. 


9 


EDITFIX  PARAMETERS 


/X5EDITFIXX5PATH 


0 

, • 

1 

' ( integer  i ( TAPE  » 

,IEDIT- 

2 

,VERS«  ) 1 /DTYP- j } 

3 

1 Zl  > ( PAD  ) 

• 

PATH 

lEDIT 

VERS 

DTYP 


Pathname  of  the  program  libraries. 

Specifies  which  of  the  program  library  files 
are  to  be  recataloged. 

Specifies  the  version  number  of  the  old 
version  to  be  used.  The  default  value  of  -1 
•'backs  you  up"  one  version. 

Device  type  of  new  file. 


EDITFIX  EXAMPLE 


/ JOB 
/ USERMAC 
/ LIMIT  6AN0»3C 
/ EDITFIX  EXAHPLE/PATH/NAME 
/ EOJ 


The  above  example  shows  how  an  EDIT  user  could  move  his 
program  libraries  back  one  version  if  a file  somehow  became 
damaged  . . ' 


EDITKILL 


The  EDITKILL  macro  is  used  to  remove  an  unwanted  member 
from  the  current  0BJLI3.  This  is  necessary  if  the  user 
either  changes  the  name  of  or  deletes  a function, 
subroutine,  or  main  program  on  the  source  library. 
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EDITKILL  PARAMETERS 


! 

i 


J 

f 


/>JEDITKILL)iPATH,MEM 


,DTYP» 


TAPE 


PAD 


PATH  Pathname  of  the  program  libraries. 

MEM  Name  of  the  member  to  be  deleted  from  the 

OBJLIB. 

DTYP  Device  type  of  the  new  OBJLIB. 

EDITKILL  EXAMPLE 


/ JOB 
/ USERMAC 
/ LIMIT  BAND=3fl 

/ EDITKILL  EXAMPLE/PATH/NAMEtOUMMY 
/ EOJ 


The  above  example  deletes  the  routine  called  DUMMY  from 
the  OBJLIB  built  in  the  previous  examples. 


SMSCNVT 


Thej SMSCNVT  macro  is  used  to  insert  a $DECK  card  before 
each  routine  in  a sequential  FORTRAN  source  file.  It  also 
permits  users  to  specify  files  which  will  be  inserted  before 
or  after  the  output  file  produced  by  SMSCNVT. 

SMSCNVT  PARAMETERS 


^)5SMSCNVT>J INPI LE , OUTPILE  I , PRON'>^name>,  BACK-<;name>, 


I 


ADD  PORTRAN  NONE 

ACTION-  ,LANG-  , USER- 

OTHER  OTHER  OTHER 


INFILE 

OUTFILE 


Access  name  of  FORTRAN  source  file. 

Access  name  of  file  to  be  produced  which 
contains  the  $DECK  cards  before  each  routine. 


1 1 
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FRONT  Access  name  of  file  which  will  be  copied  onto 
the  begining  of  OUTFILE.  If  data  cards 
follow  the  SMSCNVT  call  card,  these  cards 
will  be  used  as  the  FRONT  data  file. 

BACK  Access  name  of  file  to  be  copied  onto  the  end 

of  the  OUTFILE. 

ACTION,  Parameters  for  the  JDECK  cards. 

LANG, 

USER 


SMSCNVT  EXAMPLE 


t JOB 
I USERMAC 

f START  ACNMaCAROOECK 
PROGRAM  EXAMPL 
C 

C •••  FORTRAN  statements  ••• 

C 

END 

SUBROUTINE  A 
C 

C •••  MORE  FORTRAN  ••• 

C 

END 

FUNCTION  BCOUM) 

C 

C •••  MORE  FORTRAN  ... 

C 

END 

7 STOP 

/ SMSCNVT  CAR00ECKfE0ITIN»USER«MORAWSKI 
IMOOSET  TESTCASE 
/ FOSYS  EOITIN 
/ EOJ 

This  example  shows  how  to  use  the  SMSCNVT  macro.  The 
output  file  produced  by  the  example  is  shown  on  the  next 
page. 
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OUTPUT  FROM  THE  SMSCNVT  EXAMPLE 


iMOOSET  TESTCASE 

iOECK  A tLAMG^FOIRTRAN  tACTIONsAOO  iUSER  = M0RAUSKI 

SUBROUTINE  A 
C 

C MORE  FORTRAN  ... 

C 

END 

IOECK  B ,LANG*FORTRAN  ,ACTIfJN*AOD  ,USER  = MORAWSKI 

FUNCTION  BCDUM) 

C 

C ...  MORE  FORTRAN  ... 

C 

END 

IOECK  EXAMPL  |LANG=F0RTRAN  fACTION=AOO  »USER*MORAWSKI 
PROGRAM  EXAMPL 
C 

C ...  FORTRAN  STATEMENTS  ... 

C 

END 

COMPOSITE  EXAMPLE 

The  following  example  shows  how  to  use  SMSCNVT  and  EDIT 
together  to  produce  program  libraries  directly  from  a 
FORTRAN  deck. 


/ JOB 
/ USERMAC 
/ LIMIT  8ANO»30 
/ START  ACNMsCAROOECK 
• program  EXAMPL 
C 

C ...  FORTRAN  STATEMENTS  ... 

C 

ENO 

SUBROUTINE  A 
C 

C •••  MORE  FORTRAN  ... 

C 

ENO 

FUNCTION  BCOUM) 

C 

C •••  MORE  FORTRAN  ... 

C 

ENO 

/ STOP 

/ SMSCNVT  CAROOECK,EOITINtUSER*MORAMSKI 
IMOOSET  TESTCASE 

/ EDIT  PATHNANE*CLDfl8J*NO»OLOSRC«N1#EOTINi>UT»EaiTIN 

/ E9J 


